home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1996 March / Amiga-CD 1996 #3.iso / pd-software / mui_3.1 / developer / autodocs / mui_dataspace.doc < prev    next >
Text File  |  1996-01-19  |  5KB  |  196 lines
  1. TABLE OF CONTENTS
  2.  
  3. Dataspace.mui/Dataspace.mui
  4. Dataspace.mui/MUIA_Dataspace_Pool
  5. Dataspace.mui/MUIM_Dataspace_Add
  6. Dataspace.mui/MUIM_Dataspace_Clear
  7. Dataspace.mui/MUIM_Dataspace_Merge
  8. Dataspace.mui/MUIM_Dataspace_ReadIFF
  9. Dataspace.mui/MUIM_Dataspace_Remove
  10. Dataspace.mui/MUIM_Dataspace_WriteIFF
  11. Dataspace.mui/Dataspace.mui
  12.  
  13.     The Dataspace class serves as a very simple container for
  14.     all kinds of data. You can add data items and reference them
  15.     later through an ID. Furthermore, Dataspace class features
  16.     methods to import/export a complete Dataspace from/to an IFF
  17.     file handle.
  18.  
  19.     MUI uses subclasses of dataspace class to handle all its
  20.     configuration data and thats probably the main purpose of a
  21.     dataspace.
  22. Dataspace.mui/MUIA_Dataspace_Pool
  23.  
  24.     NAME
  25.     MUIA_Dataspace_Pool -- (V11) [I..], APTR
  26.  
  27.     FUNCTION
  28.     If you specify a memory pool from exec.library/CreatePool()
  29.     here, the dataspace object will use this pool for all its
  30.     entries.
  31.  
  32.     If you omit this tag or pass NULL, the dataspace object
  33.     will create its own memory pool instead.
  34.  
  35.     SEE ALSO
  36.     MUIM_Dataspace_Add, exec.library/CreatePool
  37. Dataspace.mui/MUIM_Dataspace_Add
  38.  
  39.     NAME
  40.     MUIM_Dataspace_Add (V11)
  41.  
  42.     SYNOPSIS
  43.     DoMethod(obj,MUIM_Dataspace_Add,APTR data, LONG len, ULONG id);
  44.  
  45.    FUNCTION
  46.     This method adds a new entry to the dataspace. If an entry
  47.     with the same ID already exists, it will be replaced with
  48.     the new entry.
  49.  
  50.     INPUTS
  51.     data - pointer to a data
  52.     len  - length of data
  53.     id   - reference id
  54.  
  55.     RESULT
  56.     Returns NULL on failure (probably because of a memory
  57.     shortage) or some non NULL value on success.
  58.  
  59.     SEE ALSO
  60.     MUIM_Dataspace_Remove, MUIM_Dataspace_Find
  61. Dataspace.mui/MUIM_Dataspace_Clear
  62.  
  63.     NAME
  64.     MUIM_Dataspace_Clear (V11)
  65.  
  66.     SYNOPSIS
  67.     DoMethod(obj,MUIM_Dataspace_Clear,);
  68.  
  69.    FUNCTION
  70.     This method clears all the contents of a dataspace. Depending
  71.     on the state of the memory pool that the dataspace object uses,
  72.     this may or may not result in more free memory.
  73.  
  74.     INPUTS
  75.     none
  76.  
  77.     RESULT
  78.     All entries will be removed from the dataspace.
  79.     The return value of this method is currently undefined.
  80.  
  81.     SEE ALSO
  82.     MUIM_Dataspace_Add, MUIM_Dataspace_Remove,
  83.     MUIM_Dataspace_Merge
  84. Dataspace.mui/MUIM_Dataspace_Merge
  85.  
  86.     NAME
  87.     MUIM_Dataspace_Merge (V11)
  88.  
  89.     SYNOPSIS
  90.     DoMethod(obj,MUIM_Dataspace_Merge,Object *dataspace);
  91.  
  92.    FUNCTION
  93.     This method adds all the contents of the merge dataspace
  94.     specified as parameter to the objects dataspace.
  95.     As with MUIM_Dataspace_Add, entries with equal IDs
  96.         will be replaced.
  97.  
  98.     INPUTS
  99.     dataspace - dataspace objects whichs contents should
  100.                 be merged.
  101.  
  102.     RESULT
  103.     Returns the number of entries that have been
  104.     added/replaced in the objects dataspace. If this
  105.     number doesnt match the number of entries in the
  106.     merge dataspace, something probably went wrong.
  107.  
  108.     SEE ALSO
  109.     MUIM_Dataspace_Add, MUIM_Dataspace_Remove
  110. Dataspace.mui/MUIM_Dataspace_ReadIFF
  111.  
  112.     NAME
  113.     MUIM_Dataspace_ReadIFF (V11)
  114.  
  115.     SYNOPSIS
  116.     DoMethod(obj,MUIM_Dataspace_ReadIFF,struct IFFHandle *handle);
  117.  
  118.     FUNCTION
  119.     Adds the contents of an IFF handle from iffparse.library to
  120.     the dataspace. As always, objects with the same ID that
  121.     are already in the dataspace will be replaced.
  122.  
  123.     This method does not look for any chunk types and chunk ids
  124.     itself. Instead, it expects that you have already located
  125.     the chunk which contains your data and does nothing
  126.     but ReadChunkBytes() until all dataspace entries of
  127.     the current chunk are read.
  128.  
  129.     NOTES
  130.     Do not call MUIM_Dataspace_ReadIFF if your handle is
  131.     positioned on chunks that were not written with 
  132.     MUIM_Dataspace_WriteIFF or strange things may happen!
  133.  
  134.     INPUTS
  135.     handle - pointer to a struct IFFHandle from
  136.              iffparse.library/AllocIFF(). The handle must
  137.              already be open, initialized for reading and
  138.              positioned on a chunk that was created with
  139.              MUIM_Dataspace_WriteIFF.
  140.  
  141.     RESULT
  142.     Returns 0 on success or some IFFERR_xxx on failure.
  143.  
  144.     SEE ALSO
  145.     MUIM_Dataspace_ReadIFF, iffparse.library/AllocIFF
  146. Dataspace.mui/MUIM_Dataspace_Remove
  147.  
  148.     NAME
  149.     MUIM_Dataspace_Remove (V11)
  150.  
  151.     SYNOPSIS
  152.     DoMethod(obj,MUIM_Dataspace_Remove,ULONG id);
  153.  
  154.    FUNCTION
  155.     This method removes an entry from the dataspace.
  156.  
  157.     INPUTS
  158.     id - reference id
  159.  
  160.     RESULT
  161.     Returns NULL if no entry with the given ID was found
  162.     in the dataspace or some non NULL value on success.
  163.  
  164.     SEE ALSO
  165.     MUIM_Dataspace_Add, MUIM_Dataspace_Find
  166. Dataspace.mui/MUIM_Dataspace_WriteIFF
  167.  
  168.     NAME
  169.     MUIM_Dataspace_WriteIFF (V11)
  170.  
  171.     SYNOPSIS
  172.     DoMethod(obj,MUIM_Dataspace_WriteIFF,struct IFFHandle *handle, ULONG type, ULONG id);
  173.  
  174.     FUNCTION
  175.     Writes the contents of a dataspace to an IFF handle of
  176.     iffparse.library.
  177.  
  178.     In detail, a chunk with the specified type and id is created
  179.     with PushChunk(), the contents of the dataspace are written
  180.     with WriteChunkBytes() and the chunk is terminated with
  181.     PopChunk().
  182.  
  183.     INPUTS
  184.     handle - pointer to a struct IFFHandle from
  185.              iffparse.library/AllocIFF(). The handle must
  186.              already be open and initialized for writing.
  187.  
  188.     type   - type of chunk to create
  189.     id     - id of chunk to create
  190.  
  191.     RESULT
  192.     Returns 0 on success or some IFFERR_xxx on failure.
  193.  
  194.     SEE ALSO
  195.     MUIM_Dataspace_ReadIFF, iffparse.library/AllocIFF
  196.